home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Format CD 23
/
Amiga Format AFCD23 (Feb 1998, Issue 107).iso
/
-seriously_amiga-
/
shareware
/
misc
/
amigaguide_htw
/
aghtw_part2
(
.txt
)
< prev
next >
Wrap
Amigaguide Document
|
1997-12-12
|
43KB
|
745 lines
@DATABASE "AGHTW-Part2"
@$VER: Amigaguide_How_To_Write_Pt2 01.04 (05.12.97) Copyright
1997 Frank P. Bunton
@INDEX "AGHTW_Index/Index"
@NODE "MAIN" "How To Write AG - Part 2"
@TOC "AGHTW_Index/Main"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS - PART 2@{UB}@{UU}
@{JLEFT}
This node should not normally be displayed if you started off from the
index file. But in case you started off this file as an individual document,
you can now access the following items:-
@{JCENTER}
@{" Making Links With Label Commands " LINK "MakingLinks"}
@{" Commands Available " LINK "Commands"}
@{" Paths Names With File Names " LINK "PathNames"}
@{" Links to Document Nodes " LINK "LinkCommand"}
@{" Links To Nodes In Other AG Documents " LINK "OtherDocs"}
@{" Links to Non Amigaguide Documents " LINK "NonGuideDocs"}
@{" ALINK Command " LINK "ALink"}
@{" Links to Other File Types - v39+ " LINK "OtherLinks"}
@{" - In Early Versions Of Amigaguide " LINK "OtherLinksEarly"}
@{" Links To External Commands " LINK "ExternalCommands"}
@{" SYSTEM Command " LINK "System"}
@{" SYSTEM Examples " LINK "SystemExamples"}
@{" Using RUN With SYSTEM Command " LINK "SystemRun"}
@{" RX Command " LINK "Rx"}
@{" RXS Command " LINK "Rxs"}
@{" ONOPEN & ONCLOSE Commands " LINK "OnOpenClose"}
@{" Links To Quit & Close " LINK "QuitClose"}
@{" Link To BEEP " LINK "Beep"}
@{" MAIN INDEX " LINK "AGHTW_Index/Main"}
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "MakingLinks" "How To Write AG - Making Links (Pt2)"
@TOC "AGHTW_Index/Contents"
@PREV "AGHTW_Part1/MainNode"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
MAKING LINKS WITH LABEL COMMANDS@{UB}@{UU}
@{JLEFT}
One of the most powerful features of a hypertext program like Amigaguide is
its ability to jump to @{"nodes" LINK "AGHTW_Part5/Nodes"} of the @{"same document" LINK "LinkCommand"24} or @{"other documents" LINK "OtherDocs"}, to
@{"load files" LINK "OtherLinks"} other than text files or to carry out @{"external commands" LINK "ExternalCommands"}.
This is all done with @{B}buttons@{UB} that set up the links.
A button is set up in this way:-
\@{"Text For Button" COMMAND "Command Argument"}
@{B}@{U}Let's break this up into its parts@{UB}.@{UU}
First is the @{"@ sign" LINK "AGHTW_Part1/Inserting"8} to indicate that what follows is an Amigaguide command.
The whole of the link command must be enclosed in curly brackets {}.
You @{B}MUST@{UB} ensure that there is no space between the \@{ and the first "
(Please read @{"Problem 5" LINK "AGHTW_Part5/Problems"120} for details).
Next comes a @{B}LABEL@{UB} (e.g. the "Text For Button" above) which is the text
displayed in the document. It would appear like this:-
@{"Text For Button" LINK "Ha"} (This is a false label so no point in clicking it!!)
@{B}The label MUST be enclosed in inverted commas!!@{UB}
Then comes the COMMAND which can be one of those listed in the @{"table below" LINK "Commands"}.
Note that there @{B}MUST@{UB} be a space on either side of the COMMAND so that the
inverted commas are not right up against either side of it. For example, all
of these are @{B}WRONG@{UB}:-
\@{"Text For Button"COMMAND "Command Argument"}
\@{"Text For Button" COMMAND"Command Argument"}
\@{"Text For Button"COMMAND"Command Argument"}
and this is @{B}CORRECT@{UB}:-
\@{"Text For Button" COMMAND "Command Argument"}
Finally comes the @{B}command's argument@{UB}. An "argument" is some text which tells
the command the way in which it is to act.
This argument will depend on the type of COMMAND being used as indicated in
the @{"table below" LINK "Commands"}.
If a Command Argument has spaces then @{B}it MUST enclosed in inverted commas@{UB}.
Command arguments without spaces do not need inverted commas but I would
advise you to get into the habit of always using them so that you will not
forget to put them in if needed.
Sometimes you have labels set out in a table like this:-
@{"First Label" LINK "Ha"}
@{"Second label" LINK "Ha"} (More false labels)
@{"Third Label" LINK "Ha"}
The above display looks a bit tatty so I usually do it like this:-
\@{" First Label " COMMAND "Command Argument"}
\@{" Second label " COMMAND "Command Argument"}
\@{" Third Label " COMMAND "Command Argument"}
which would look like this:-
@{" First Label " LINK "Ha"}
@{" Second Label " LINK "Ha"} (More false labels)
@{" Third Label " LINK "Ha"}
Note the placement of the spaces in the LABEL text to give equal sized
buttons for each link and the extra space at the start and end of the text
to give it a better appearance.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "Commands" "How To Write AG - Commands To Use With Links (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
COMMANDS AVAILABLE FOR USE WITH LABELS@{UB}@{UU}
@{JLEFT}
The following commands can be when @{"making links" LINK "MakingLinks"}:-
@{U}COMMAND@{UU} @{U} Argument @{UU} @{U}Actions that Will Take Place@{UU}
@{" LINK " LINK "LinkCommand"} Node Name Jump to the node
@{" ALINK " LINK "ALink"} Node Name Jump to the node
@{" SYSTEM " LINK "System"} AmigaDOS Command Execute the AmigaDOS Command
@{" RX " LINK "Rx"} ARexx Script Name Execute the ARexx Script
@{" RXS " LINK "Rxs"} ARexx Instruction Execute the ARexx Instruction
@{" QUIT " LINK "QuitClose"} None Quit Amigaguide
@{" CLOSE " LINK "QuitClose"} None Close the Amigaguide window
@{" BEEP " LINK "Beep"} None Operate the Amiga Alert
"COMMAND" and "Argument" are used in these positions in the button set up:-
\@{"Text For Button" COMMAND "Command Argument"}
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "PathNames" "How To Write AG - File Names and path Names (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
INCLUSION OF PATH NAMES WITH FILE NAMES@{UB}@{UU}
@{JLEFT}
When making links to:-
@{" Nodes within other documents " LINK "OtherDocs"}
@{" Other file types " LINK "OtherLinks"}
@{" External commands with SYSTEM " LINK "System"}
@{" ARexx scripts using RX " LINK "Rx"}
it may be necessary, when calling the file, to include the full path name or
a partial path name to the file. At other times, the file name without any
path can be used.
@{B}IF YOU ARE IN ANY DOUBT@{UB} then it would be safest to use the @{B}FULL path name@{UB} as
you will then avoid the slip ups that can occur when a file name is used on
its own or with a partial path name.
@{B}@{U}Using a File Name Without Any Path Name@{UB}@{UU}, for example:-
\@{"Button Name" LINK "filename"}
This can be done if you are @{B}absolutely sure that "FileName" is in the
directory being recognised by Amigaguide/Multiview as its@{UB} @{"Current Directory" LINK "AGHTW_Part1/CD"}.
If "FileName" is in a directory other than Amigaguide/Multiview's current
directory then you should use the full path name except in cases outlined in
the next section "Partial Path Name".
@{B}@{U}Using a File Name With a Partial Path Name@{UB}@{UU}, for example:-
\@{"Button Name" LINK "DirectoryName/FileName"}
This can be done if "DirectoryName" is a sub directory of Amigaguide's or
Multiview's @{"current directory" LINK "AGHTW_Part1/CD"}.
@{B}@{U}Using The Full Path Name@{UB}@{UU}, for example:-
\@{"Button Name" LINK "DiskName:DirectoryName/FileName"}
This should be done in all cases other than the two outlined above.
It should also be used when there is any doubt as to what to do!!!
It is certainly the @{B}SAFEST WAY!!!@{UB}
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "LinkCommand" "How To Write AG - Links To Document Nodes (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
LINKS TO DOCUMENT NODES
THE LINK COMMAND
All Versions - LOCAL Command@{UB}@{UU}
@{JLEFT}
(See also @{"Making Links" LINK "MakingLinks"} and @{"ALINK" LINK "ALink"}.)
The LINK command can be used to jump to:-
* Nodes in the same Amigaguide document (this section)
* @{" Nodes In Other Amigaguide Documents " LINK "OtherDocs"}
* @{" Non Amigaguide Documents " LINK "NonGuideDocs"}
* @{" Files of Other (non Document) Types " LINK "OtherLinks"}
The @{"basic Amigaguide document" LINK "AGHTW_Part1/Getting"} that I discussed had only one @{"node" LINK "AGHTW_Part5/Nodes"} which is
usually not enough. So to have more than one node, you need to set up some
links to the other nodes.
I have already discussed how to set up links under the heading @{"MakingLinks" LINK "MakingLinks"}.
To link to other nodes in the same document you use the LINK command as
illustrated by:-
\@{"Label Text" LINK "NodeName"}
\@{"Label Text" LINK "NodeName"<LineNumber>}
If "LineNumber" is used the link will put that line number at the top of the
window instead of the first line of the node. For example:-
\@{"problem 3" LINK "AGHTW_Part5/Problems"52} and
\@{"problem 4" LINK "AGHTW_Part5/Problems"97}
(The above is all in one @{"physical line" LINK "AGHTW_Part5/Physical"} when illustrated 5 lines below.)
This would put line number 52 and line 97 respectively of the node "Problems"
at the top of the window. The above line would look like this:-
@{"problem 3" LINK "AGHTW_Part5/Problems"52} and @{"problem 4" LINK "AGHTW_Part5/Problems"97}
Please read about these problems now as they relate to this topic.
Another problem is that version 34 seems to start the line count at 1 and
version 39 & 40 at 0 (zero) so that if you click on "Problem 3" and
"Problem 4" above:-
- with version 39 & 40 the first lines of the problems will be one below
the top
- with version 34 the first lines of the problems will be at the top
I have purposely done it like this as most cross references in this document
start with a blank line above the target line thus allowing users of both
version 34 and versions 39/40 to easily see the reference. However, at times,
users of version 34 will have to scroll up one line to see the target line.
(Oh for @{"my suggestion" LINK "AGHTW_Part5/Problems"97} about aiming at targets instead of line numbers!!)
If the node to be reached is in the same document then the above is all that
is needed. For example, to jump to the MAIN node of this document (which is
@{"not normally visible" LINK "AGHTW_Part1/MainNode"30}) you could use:-
Click on \@{"Main Node" LINK "Main"} to read main node.
which would appear like this (what you will see is @{"explained here" LINK "AGHTW_Part1/MainNode"30}):-
Click on @{"Main Node" LINK "Main"} to read main node.
The LINK command can be used in a line of text (as shown above) or in a menu
type situation as is used in the @{"Main Node" LINK "Main"} of this document (normally
invisible) which is set up like this:-
\@{" Making Links With Label Commands " LINK "MakingLinks"}
\@{" Commands Available " LINK "Commands"}
\@{" Paths Names With File Names " LINK "PathNames"}
\@{" Links to Document Nodes " LINK "LinkCommand"}
\@{" Links To Nodes In Other AG Documents " LINK "OtherDocs"}
\@{" Links to Non Amigaguide Documents " LINK "NonGuideDocs"}
\@{" ALINK Command " LINK "ALink"}
\@{" Links to Other File Types - v39+ " LINK "OtherLinks"}
\@{" - In Early Versions Of Amigaguide " LINK "OtherLinksEarly"}
\@{" Links To External Commands " LINK "ExternalCommands"}
\@{" SYSTEM Command " LINK "System"}
\@{" SYSTEM Examples " LINK "SystemExamples"}
\@{" Using RUN With SYSTEM Command " LINK "SystemRun"}
\@{" RX Command " LINK "Rx"}
\@{" RXS Command " LINK "Rxs"}
\@{" ONOPEN & ONCLOSE Commands " LINK "OnOpenClose"}
\@{" Links To Quit & Close " LINK "QuitClose"}
\@{" Link To BEEP " LINK "Beep"}
Note the extra spaces in the labels the use of which was @{"discussed earlier" LINK "MakingLinks"56}.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "OtherDocs" "How To Write AG - Links To Other AG Document Nodes (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
LINKS TO DOCUMENT NODES
LINKS TO OTHER AMIGAGUIDE STYLE DOCUMENTS@{UB}@{UU}
@{JLEFT}
(See also @{"Links to Non Amigaguide Documents" LINK "NonGuideDocs"}).
As well as having node @{"links within the document" LINK "LinkCommand"24} you can also have links
to nodes on other documents. This is done by specifying the @{"PATH to the file" LINK "PathNames"}
containing the node as well as the node name itself.
To illustrate how to do it let's make these assumptions:-
* The documents are in a directory called "Help" which is in an assigned
directory called "MyProgram:". The path to the help directory is
therefore:-
MyProgram:Help
* The document to be called up is called "ExtraNotes" so that its full
path name is:-
MyProgram:Help/ExtraNotes
* The node to be viewed within the document "ExtraNotes" is called
"Something"
To call up this node with a label name of "Help With Something" you would
use:-
\@{"Help With Something" LINK "MyProgram:Help/ExtraNotes/Something"}
Note that the node name is added to the file path name with the same type
of path separator as the rest of the path, i.e. the / character.
The above line would appear in the text like this: @{"Help With Something" LINK "MyProgram:Help/ExtraNotes/Something"}.
If you click on this link you will most likely get a requester window asking
you to insert the volume "MyProgram" as you are unlikely to have an
assignment made to "MyProgram:" nor a disk with that name!
@{"Click here" SYSTEM "Execute Miscellaneous/AssignMyProgram"} to assign "MyProgram:" to the directory holding this file (there
will not be any visible sign of action) then go back and click on the above
button with the label "Help With Something". I have included in this archive
a directory called "Help" which contains the file "ExtraNotes" so as I can
demonstrate the above.
The above "Click here" button to do the assignment is set up like this:-
\@"Click here" SYSTEM "Execute Miscellaneous/AssignMyProgram"}
(see @{"SYSTEM" LINK "System"}) and the script file that is executed "AssignMyProgram" has
only one line which is as follows:-
Assign MyProgram: ""
Using the AmigaDOS command "Assign" in this way makes the assignment to the
current directory. This is all covered in @{"AmigaDOS For Beginners" LINK "AGHTW_Boring_Stuff/OtherDocs"7}.
I could @{B}NOT@{UB} use:-
\@"Click here" SYSTEM "Assign MyProgram: """}
because the "" after MyProgram: can not be accepted inside the inverted
commas surrounding the argument in the command \@{"Label" SYSTEM "Argument"}
@{"Click here" SYSTEM "Assign MyProgram:"} to remove the assignment to "MyProgram:" (again, there will be
no visible sign of action).
The above "Click here" button to remove the assignment is set up as follows:-
\@{"Click here" SYSTEM "Assign MyProgram:"}
Using "Assign" in this way removes the previously made assignment to
"MyProgram:". This time I can use the AmigaDOS command itself as the
argument to the command SYSTEM.
If you are @{B}absolutely sure that the other document is in the directory being
recognised by Amigaguide/Multiview as its@{UB} @{"Current Directory" LINK "AGHTW_Part1/CD"} then you can
omit the path name and just use the document and node name, as in:-
\@{"Help With Something" LINK "ExtraNotes/Something"}
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "NonGuideDocs" "How To Write AG - Links To Non Guide Documents (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
@{B}@{U}LINKS TO NON AMIGAGUIDE TYPE DOCUMENTS
All Versions@{UB}@{UU}
@{JLEFT}
(See also @{"Making Links" LINK "MakingLinks"}.)
Links can be made to text documents that are @{B}NOT@{UB} Amigaguide style documents,
i.e. documents without any nodes or other Amigaguide style commands.
This is done in the same way as @{"Links To Other Amigaguide Style Documents" LINK "AGHTW_Part2/OtherDocs"}.
As an example, the following line will allow you to view the
startup-sequence file on your boot disk:-
\@{"View startup-sequence file" LINK "S:Startup-Sequence/MAIN"}
which will appear in the text like this:-
@{"View startup-sequence file" LINK "S:Startup-Sequence/MAIN"}
@{B}Note that the node name "MAIN" MUST be included in the command line argument
even though it is a plain text file without any nodes!!@{UB}
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "ALink" "How To Write AG - ALink Command (Pt2)"
@TOC "AGHTW_Index/Contents"
@NEXT "OtherLinks"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
@{B}@{U}ALINK COMMAND
All Versions - LOCAL Command@{UB}@{UU}
@{JLEFT}
(See also @{"Making Links" LINK "MakingLinks"}.)
This is similar to the @{"LINK" LINK "LinkCommand"} command and should be used in the same way.
@{B}In Amigaguide version 34@{UB} the main difference is that ALINK opens the linked
node in a new window. In this new window, however, the "Retrace" button is
inactive and thus cannot be used to go back to the original window. But the
"Contents" button will go back. The original window can be closed leaving
the new window open.
@{B}In Amigaguide versions 39 and 40@{UB} it opens the node in the same window
and, as far as I can determine, is identical to LINK.
Unless you have some real need to use it, I would suggest that you do not
use this command.
To demonstrate ALINK, I have used this button set up:-
\@{"Click here for an ALINK linkage" ALINK "AlinkDemo"}
in this line:-
@{"Click here for an ALINK linkage" ALINK "AlinkDemo"}
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "ALinkDemo" "How To Write AG - ALINK Demonstration (Pt2)"
@TOC "AGHTW_Index/Contents"
@NEXT ""
@PREV ""
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
ALINK COMMAND@{UB}@{UU}
@{JLEFT}
This node was reached by an ALINK command
If you are using:-
- @{B}Version 34@{UB} - then it should be in a new window with the previous
node still showing behind it. You can reposition the
two windows so that both are visible at once.
- @{B}Version 39 or 40@{UB} - then it should have appeared in the same window as the
previous node with the previous node being replaced by
this node.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "OtherLinks" "How To Write AG - Links To Other Files Types (Pt2)"
@TOC "AGHTW_Index/Contents"
@PREV "ALink"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
LINKS TO FILES TYPES OTHER THAN DOCUMENTS
This section applies only to Versions 39 Onwards
Of MULTIVIEW with the use of DATATYPES In OS 3.x!@{UB}@{UU}
@{JLEFT}
As well as having links to @{"other AG documents" LINK "OtherDocs"} and @{"non AG documents" LINK "NonGuideDocs"}, if
your Amiga is equipped with MULTIVIEW and DATATYPES (as in Amigas using
AmigaDOS 3.0 onwards) then your Amigaguide document can have links to files
other than Amigaguide documents and plain text documents.
These other files can be things such as pictures (of various formats such
as .gif .iff .jpg), animations, sound files, etc. etc. All that is
necessary is that you have the appropriate DATATYPE file installed on your
system.
The standard datatype files that come with Workbench 3.1 are:-
8SVX For the display of IFF sound files
Amigaguide For the display of Amigaguide text files
FTXT For the display of IFF text files
ANIM For the display of ANIM-format animation files
CDXL For the display of CDXL-format animation files
ILBM For the display of bitmap picture files
These links are set up in the same way as @{"links to non AG documents" LINK "NonGuideDocs"}. For
example, to show a picture, you would use something like this:-
\@"Show picture of cat" LINK "DiskName:Pictures/cat.pic/MAIN"}
@{B}Note that the node name "MAIN" MUST be included in the command line even
though it is a picture file without any text or nodes!!@{UB}
(See also @{"Path Names" LINK "PathNames"}.)
As an example, this line:-
\@{"Show Amiga Logo" LINK "Miscellaneous/AmigaLogo.pic/MAIN"}
would appear like this:-
@{"Show Amiga Logo" LINK "Miscellaneous/AmigaLogo.pic/MAIN"} (If using v34 you may get a window full of garbage!)
and, if the file "AmigaLogo.pic" (that came with this archive) is still in
this archive's "Miscellaneous" directory, then clicking the above will
display the picture file.
Similarly, this line:-
\@{"Sound The Cuckoo" LINK "Miscellaneous/Cuckoo.snd/MAIN"}
will look like this:-
@{"Sound The Cuckoo" LINK "Miscellaneous/Cuckoo.snd/Main"} (If using v34 you may get a window full of garbage!)
and, when clicked, will open a new window with an icon that, when clicked,
will make the cuckoo sound.
(If anyone knows if it is possible to get the button the make the sound when
clicked rather than opening a new window with the icon then @{I}please @{UI}let @{"me" LINK "AGHTW_Boring_Stuff/Author"}
know! - but see @{"Links To Other File Types In Early Versions" LINK "OtherLinksEarly"}.)
There is no need to nominate the file type and/or the datatype file to use.
Multiview will automatically use the correct datatype. However, if
Multiview cannot find an appropriate datatype file in your system then you
will be given an error message in the Multiview title bar:-
Unknown datatype for ..... (filename)
@{B}@{U}See Also@{UB}@{UU} - @{"Links To Other File Types In Early Versions" LINK "OtherLinksEarly"} that I have included
mainly for users of versions of Amigaguide earlier than 39.
Users of versions 39 onwards may care to read this in case they
are writing for users of earlier versions.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "OtherLinksEarly" "How To Write AG - Links Other Files Early Versions (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
LINKS TO FILES TYPES OTHER THAN DOCUMENTS
IN EARLY VERSIONS OF AMIGAGUIDE@{UB}@{UU}
@{JLEFT}
The @{"previous section" LINK "OtherLinks"} described how to make links to file types other than
documents but this was only available in versions 39 onwards.
The method I will describe here can be used in @{B}ANY @{UB}version so if you have a
version earlier than 39, or you are writing for users of these earlier
versions, then you should use the method described below.
My thanks to @{"Christopher Jeffery" LINK "AGHTW_Boring_Stuff/Credits"5} for reminding me of this method and
suggesting its inclusion.
When you wish to load other file types without the benefit of @{"datatypes" LINK "OtherLinks"19}
you can do it by this means which calls an external program to handle the
file using the @{"SYSTEM" LINK "System"} command:-
\@{"Button Name" SYSTEM "Path/ProgramName Path/FileName"}
Where - Path/ProgramName is the @{"full path" LINK "PathNames"} and name of the utility program
that will operate the file - e.g. a picture
viewer or a sound player, and
- Path/FileName is the full path and the file name to be used.
For example, if you had a sound player called "Playsound" and a picture
viewer called "ShowPic" both in "DH0:Utilities" and you wanted to
@{"show the picture" LINK "OtherLinks"38} and @{"hear the sound" LINK "OtherLinks"50} I illustrated in the previous section,
then you could use:-
\@{"Show AmigaLogo" SYSTEM "DH0:Utilities/ShowPic Miscellaneous/AmigaLogo.pic"}
\@{"Sound The Cuckoo" SYSTEM "DH0:Utilities/PlaySound Miscellaneous/Cuckoo.snd"}
I cannot properly illustrate these as I do not know what utilities my
readers have and which directories they keep them in. This is the main draw
back with this method.
If your Amigaguide document is only for yourself then there is no problem.
But if it is meant for the use of other people then, to make it foolproof,
you would really have to include the utility programs in your archives which
would make them more bulky than necessary. You would also need to consider,
in the case of copyright utility programs, whether their distribution in
your archives is permissible or not.
For these reasons, I have not provided working examples of the above two
command lines.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "ExternalCommands" "How To Write AG - Links To External Commands (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
LINKS TO EXTERNAL COMMANDS@{UB}@{UU}
@{JLEFT}
It is possible to call up external commands from AmigaDOS and ARexx by
inserting link commands into the text.
There are five Amigaguide commands you can use for these purposes. They
are:-
@{"SYSTEM " LINK "System"} - To call up @{B}AmigaDOS commands@{UB}, or other programs that can be
run from a CLI/Shell window,
@{" RX " LINK "Rx"} - To execute an @{B}ARexx script file@{UB}.
@{" RXS " LINK "Rxs"} - To execute an @{B}ARexx instruction@{UB},
@{" ONOPEN " LINK "OnOpenClose"} - To execute an @{B}ARexx script@{UB} when a document or window is
@{B}opened@{UB},
@{" ONCLOSE " LINK "OnOpenClose"} - To execute an @{B}ARexx script@{UB} when a document or window is
@{B}closed@{UB},
I will not go into any detailed explanations of how to use AmigaDOS commands
or ARexx instructions. If you want to know more about these topics then get
hold of my other products @{"`AmigaDOS For Beginners' & `ARexx For Beginners'" LINK "AGHTW_Boring_Stuff/OtherDocs"}.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "System" "How To Write AG - The SYSTEM Command (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
THE SYSTEM COMMAND
All Versions - LOCAL Command@{UU}@{UB}
@{JLEFT}
(See also @{"Making Links" LINK "MakingLinks"}.)
This command is used as follows:-
\@{"Label Name" SYSTEM "Shell/CLI Command Line"}
See @{"`Examples Of SYSTEM'" LINK "SystemExamples"} for examples.
"@{B}Shell/CLI Command Line@{UB}" is any command line such as can be entered in a
Shell/CLI window and can be:-
- any @{B}AmigaDOS command@{UB} with its appropriate arguments, or
- the name of an @{B}independent program @{UB}(non-AmigaDOS) that is capable of
being run from Shell/CLI.
In other words, it can be anything that you can normally enter at the prompt
in a Shell/CLI window.
There will be times when you need to use the AmigaDOS command RUN at the
start of the command line argument as in:-
\@{"Label Name" SYSTEM "RUN Shell/CLI Command Line"}
See @{"`Using RUN With SYSTEM'" LINK "SystemRun"} for explanation.
@{B}AmigaDOS commands@{UB} do @{B}NOT@{UB}, in general, create their own input and/or output
(I/O) windows. (There are a few exceptions to this rule such as Newshell,
Requestfile and Ed.) They use the CLI window in which they are activated.
(By "AmigaDOS Command" I mean the commands in the "C:" directory and @{B}NOT@{UB} the
programs in other directories on the Workbench disk which generally @{B}DO @{UB}
create their own I/O windows.)
So if you use, as the SYSTEM argument, an @{B}AmigaDOS command@{UB} that needs to
have an I/O window then, if the Amigaguide document was started from:-
- @{B}a Workbench icon@{UB} - there will be no appropriate I/O window and thus
the input will not be possible and
the output will not be seen
- @{B}a Shell/CLI window@{UB} - then that Shell or CLI window will be used
as the I/O window for the command.
The same cannot normally be said about independent (non AmigaDOS) programs
as most provide their own I/O windows. However, some can only be started
from Shell/CLI and do not provide their own I/O windows. In these cases,
the above will apply.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "SystemExamples" "How To Write AG - The SYSTEM Command Examples (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
EXAMPLES OF THE THE SYSTEM COMMAND@{UB}@{UU}
@{JLEFT}
As an example of SYSTEM, a label such the following one would allow the
reader to open a new Shell/CLI window:-
\@{"Open New Shell/CLI Window" SYSTEM "Newshell"}
and the label would appear in the document like this:-
@{"Open New Shell/CLI Window" SYSTEM "Newshell"}
An AmigaDOS script file could be made to run in this shell window by using:-
\@{"Open New Shell/CLI Window" SYSTEM "Newshell FROM Path/ScriptName"}
This technique could be used to provide an @{"input/output window" LINK "System"33} for your
AmigaDOS commands. For example, this command line:-
\@{"Click here to start script" SYSTEM "Newshell
CON:0/10/640/100/DemoScript/CLOSE FROM Miscellaneous/DemoScript"}
(All the above is in the one line!)
It would appear like this:-
@{"Click here to start script" SYSTEM "Newshell CON:0/10/640/100/DemoScript/CLOSE FROM Miscellaneous/DemoScript"}
and, if you still have the file "DemoScript" in the "Miscellaneous"
directory of this set, (it came in the same archive) then clicking on this
button should cause the script to be executed. @{"Click here" LINK "Miscellaneous/DemoScript/MAIN"} to read the
script itself.
There are also some examples of SYSTEM in the @{"`Links To Other Documents'" LINK "OtherDocs"49}
section.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "SystemRun" "How To Write AG - Using RUN With The SYSTEM Command (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
USING RUN WITH THE SYSTEM COMMAND
All Versions - LOCAL Command@{UU}@{UB}
@{JLEFT}
You should note that sometimes it is necessary to use RUN in the SYSTEM
argument:-
\@{"Label Name" SYSTEM "RUN Shell/CLI Command Line"}
To demonstrate the difference between using RUN and not using RUN I will
use the "Clock" program which, to the best of my knowledge, is a standard
program in the "Utilities" draw of @{B}ALL@{UB} Amiga Workbench versions. To activate
the clock we could use:-
\@{"Start Clock" SYSTEM "Sys:Utilities/Clock"}
which would look like this:-
@{"Start Clock" SYSTEM "Sys:Utilities/Clock"}
If you click on this button and no clock appears then you may have moved
your clock to another directory or deleted it altogether!
With the clock running, what happens next depends on the Amigaguide version
being used.
With @{B}Version 34@{UB}, if the Amigaguide window is selected the mouse pointer goes
to sleep and the Amigaguide window is completely unusable until the clock
program is exited.
With @{B}Versions 39 & 40@{UB}, if the Amigaguide/Multiview window is selected, the
mouse @{B}does not@{UB} go to sleep and the window can still be scrolled up and down
but the link buttons will not work until the clock is exited.
To prevent this type of hold up we need to ensure that the clock is started
using the RUN command as illustrated by this example:-
\@{"Start Clock With RUN" SYSTEM "RUN Sys:Utilities/Clock"}
which would look like this:-
@{"Start Clock With RUN" SYSTEM "RUN Sys:Utilities/Clock"}
Now the reader can continue to use the Amigaguide document while the clock
continues running.
@{B}When to Use Or Not Use RUN@{UB}
Use RUN if you want the reader to be able to continue reading the document
while the program continues to run.
Do NOT use RUN if you wish the program to finish its function before the
reader continues with the document.
But remember that some programs will detach themselves from the process in
which they were started and act as if RUN was used even if it wasn't used!
This is illustrated by the NEWSHELL command @{"used above" LINK "SystemExamples"}.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "Rx" "How To Write AG - The RX Command (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
THE RX COMMAND - LINKS TO AREXX SCRIPTS
All Versions - LOCAL Command@{UU}@{UB}
@{JLEFT}
(See also @{"Making Links" LINK "MakingLinks"} and @{"Links To ARexx Instructions" LINK "Rxs"}.)
This command will allow the execution of an ARexx script file. It is used
like this:-
\@{"Text for Button" RX "MyDisk:ARexx_Scripts/ScriptName.rexx"}
The above line would appear in the text as follows:-
@{"Text for Button" RX "MyDisk:ARexx_Scripts/ScriptName.rexx"} (This is a false label. Clicking on it will get you
nothing except a file requester to insert MyDisk:!!)
Unless the script file is in the @{"current directory" LINK "AGHTW_Part1/CD"} being recognised by
Amigaguide/Multiview, the @{"full path name" LINK "PathNames"38} for the file, or maybe a
@{"partial path name" LINK "PathNames"31}, should be used. An example using a partial file name is:-
\@{"Run Test ARexx Program" RX "Miscellaneous/TestProgram"}
This button appears like this:-
@{"Run Test ARexx Program" RX "Miscellaneous/TestProgram"}
To use this button, you should make sure the file "TestProgram.guide" is
still in the "Miscellaneous" directory. @{"Click here" LINK "Miscellaneous/TestProgram.guide/MAIN"} to read the ARexx script
"TestProgram.guide" that is linked to the above button.
Note that the ARexx script file name suffix is ".guide" and not ".rexx"
as Amigaguide/Multiview look for files with the ".guide" suffix when a file
name without a suffix is used. Thus we do not need to include the suffix in
the file name used in the command line.
If the script file name had any other suffix but ".guide" then you would
have to include the suffix in the command line. For example:-
\@{"Run Test ARexx Program" RX "Miscellaneous/TestProgram.rexx"}
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "Rxs" "How To Write AG - The RXS Command (Pt2)"
@TOC "AGHTW_Index/Contents"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
THE RXS COMMAND - LINKS TO AREXX INSTRUCTIONS
All Versions - LOCAL Command@{UU}@{UB}
@{JLEFT}
(See also @{"Making Links" LINK "MakingLinks"} and @{"Links To ARexx Scripts" LINK "Rx"}.)
This command allows an ARexx instruction string to be included as the
action to be carried out when the button is clicked.
An "ARexx instruction string" consists of an ARexx instruction together
with its arguments. Note that the way in which this is different to RX is
that RX calls an external ARexx script file and RXS has all the ARexx
instructions in the one line embedded within the button.
It is used like this:-
\@{"Text for button" RXS "ARexx instruction string"}
To give an example, I will include the ARexx instruction ADDRESS which
tells ARexx to talk to an external program, in this case AmigaDOS which has
an ARexx port name of "COMMAND". The AmigaDOS command "NewShell" is then
sent to AmigaDOS and a new shell window should appear. This is how it would
be set up:-
\@{"Click to open new shell" RXS "ADDRESS 'COMMAND' 'NewShell'"}
and it would appear like this:-
@{"Click to open new shell" RXS "ADDRESS 'COMMAND' 'NewShell'"}
(This is a bit pointless as you could just use the SYSTEM command as we did
@{"earlier" LINK "SystemExamples"5} but it is a simple way of demonstrating RXS.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "OnOpenClose" "How To Write AG - The ONOPEN & ONCLOSE Commands (Pt2)"
@TOC "AGHTW_Index/Contents"
@NEXT "QuitClose"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
THE ONOPEN & ONCLOSE COMMANDS
Version 40 - LOCAL and GLOBAL Commands@{UU}@{UB}
@{JLEFT}
These two commands will cause an ARexx script to be executed when a
document or window is opened or when it closed respectively.
When used as @{B}global@{UB} commands:-
- ONOPEN executes the ARexx script immediately after Amigaguide or
Multiview is started and before the display window is opened.
- ONCLOSE executes the ARexx script after the CLOSE gadget is clicked or
the "Project/Quit" menu item is selected but before the display
window is closed.
When used as @{B}local@{UB} commands:-
- ONOPEN executes the ARexx script before the node window in which it is
contained is opened.
- ONCLOSE executes the ARexx script when the node window in which it is in
is exited but just before it goes to the next or previous node.
This could happen when one of the Amigaguide window buttons
("Retrace" etc.) is selected or the close gadget is clicked.
The way they are used is as follows:-
#ONOPEN "Path/filename of ARexx Script" (remember that @{"# = @" LINK "AGHTW_Part1/Important"})
#ONCLOSE "Path/filename of ARexx Script"
The scripts for ONOPEN and ONCLOSE can be the same or different.
If you are @{B}absolutely sure that the ARexx script is in the directory being
recognised by Amigaguide/Multiview as its@{UB} @{"Current Directory" LINK "AGHTW_Part1/CD"} then you can
omit the @{"full path name" LINK "PathNames"38} and just use the script name. Or you can use a
@{"partial path name" LINK "PathNames"31}, as in the following two examples lines which are in the
node that you will reach when you @{"click here" LINK "OnExample"}:-
#ONOPEN "Miscellaneous/TestProgram_Open" (remember that @{"# = @" LINK "AGHTW_Part1/Important"})
#ONCLOSE "Miscellaneous/Testprogram_Close"
When I discussed @{"RX" LINK "Rx"33} I said that RX would recognise the ".guide" suffix.
For some strange reason, the ONOPEN and ONCLOSE will @{B}NOT@{UB} recognise
".guide" but will recognise the ".rexx" suffix. The above two script files
are therefore in this archive with the names:-
Miscellaneous/TestProgram_Open.rexx
Miscellaneous/Testprogram_Close.rexx
@{"Click here" LINK "Miscellaneous/TestProgram_Open.rexx/MAIN"} to read the "TestProgram_Open.rexx" script.
@{"Click here" LINK "Miscellaneous/TestProgram_Close.rexx/MAIN"} to read the "TestProgram_Close.rexx" script.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "OnExample" "How To Write AG - Example ONOPEN ONCLOSE (Pt2)"
@ONOPEN "Miscellaneous/TestProgram_Open"
@ONCLOSE "Miscellaneous/Testprogram_Close"
@TOC "AGHTW_Index/Contents"
@NEXT ""
@PREV ""
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
EXAMPLE OF THE ONOPEN AND ONCLOSE COMMANDS@{UB}@{UU}
@{JLEFT}
If you are using Amigaguide version 40 onwards you should have seen a
window open briefly just before this node window opened. You will see
another window open briefly when you exit this node.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "QuitClose" "How To Write AG - Quit & Close Links (Pt2)"
@TOC "AGHTW_Index/Contents"
@PREV "OnOpenClose"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
LINKS TO QUIT AND CLOSE
QUIT & CLOSE COMMANDS
Version 34 - LOCAL Command@{UB}@{UU}
@{JLEFT}
(See also @{"Making Links" LINK "MakingLinks"}.)
These commands create buttons that, when clicked, will close the Amigaguide
window in which they appear. They are used like this:-
\@{"Text for button" QUIT}
\@{"Text for button" CLOSE}
Note that there is no @{"argument" LINK "Commands"} for these two commands.
The difference between to two is that:-
- "CLOSE" will only close the window in which it appears. For example, if
other windows have been opened with @{"ALINK" LINK "ALink"} then "CLOSE" only closes that
window in which it appears and leaves OPEN all other windows connected
with the original document.
- "QUIT" will close ALL windows opened from the original document as well
as the original document's window no matter which window it appears in.
@{B}@{U}Comment For Version 39@{UB}@{UU}
Buttons set up in this way will @{B}NOT APPEAR@{UB} when viewed with Amigaguide or
Multiview version 39.
@{B}@{U}Warning For Version 40@{UB}@{UU}
I will NOT include demonstration buttons here as their use creates problems
in version 40. For example, if buttons using these commands are included,
and the reader clicks on the buttons, then everything freezes up. You can no
longer use the buttons at the top of the Amigaguide document (e.g. "Retrace"
"Contents" etc.) But fortunately, the close gadget still works!
Even if you are using version 34 (which is the only version in which they
work) I would suggest that you DO NOT use QUIT and CLOSE in case anyone
reading your documents is using later versions or in case you upgrade your
own Amiga.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "Beep" "How To Write AG - Link To Beep (Pt2)"
@TOC "AGHTW_Index/Contents"
@NEXT "AGHTW_Part3/GlobalLocal"
@{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS
LINK TO BEEP
All Versions EXCEPT 39 - LOCAL Command@{UB}@{UU}
@{JLEFT}
(See also @{"Making Links" LINK "MakingLinks"}.)
The BEEP command links to the Amiga's alert signal. This signal can be a
screen flash (in all AmigaDOS versions) or, in AmigaDOS v2.1 onwards, a
flash and/or a sound depending on how you have your SOUND preference set up.
You can set up a beep button like this:-
\@{"Button Text" Beep}
(There is no @{"argument" LINK "Commands"} for this command.)
The above example would appear as shown below between the arrows:-
--> @{"Button Text" Beep} <--
If you are using Amigaguide/Multiview version 39 then you will probably @{B}NOT@{UB}
see a button between the two arrows but users of versions 34 and 40 should
be able to see and use the button.
Clicking on the button should activate the Amiga's alert.
It is interesting to note that, in version 34, @{"ANY unrecognised command" LINK "AGHTW_Part1/Unrecognised"} will
activate the Amiga's alert signal.
Please @{UI}let @{"me" LINK "AGHTW_Boring_Stuff/Author"} know if you know of any use for the BEEP command because I
cannot think of any!!
Thanks to @{"Oleg Sergeev" LINK "AGHTW_Boring_Stuff/Credits"27} for telling me about this command.
@{JCENTER}=== End of Text ===
@ENDNODE
@NODE "Ha" "Gotcha!! (Pt2)"
@TOC "AGHTW_Index/Contents"
@NEXT ""
@PREV ""
@{JCENTER}
HA!! I knew you couldn't resist clicking on the "false" label!
@{JCENTER}=== End of Text ===
@ENDNODE
(.txt)
(.txt)